Skip to content

Stop discarding calls over values the caller never wrote - #292

Merged
hffmnnj merged 19 commits into
feat/high-risk-tool-contractsfrom
feat/empty-string-boundary
Aug 5, 2026
Merged

hffmnnj merged 19 commits into
feat/high-risk-tool-contractsfrom
feat/empty-string-boundary

Conversation

@hffmnnj

@hffmnnj hffmnnj commented Aug 4, 2026 •

Copy link
Copy Markdown
Owner

Fixes the single largest source of failed tool calls in this codebase, then brings twelve more tools into conformance with the House Tool-Description Standard. Stacked on #291.

The behavior change

Agents calling these tools kept hitting rejections caused by arguments they never authored. A call meant as { wave_number: 3, verifications: [...] } would arrive as { wave_number: 3, status: "", task_updates: [{ task_index: 0, status: "" }], verifications: [...] }. The tool then rejected it for a conflict the caller never created.

This was fixed rather than documented because documenting it was tried first and measurably failed. #291 rewrote goop_write_wave's description specifically to warn against passing empty strings. The very next agent to call that tool failed the same way and could not record its verification rows at all. An earlier one failed after being warned directly in its instructions. Five occurrences, two of them after the fix meant to prevent them.

The reason is structural: the empty strings are introduced during call serialization, after the caller's intent is already gone. No description can reach that layer.

So the boundary now treats an exact empty string as absent, before any tool logic runs, on both the V1 and V2 host paths from one shared seam.

What is deliberately not coalesced

Some fields genuinely mean something when empty, and coalescing those would convert an intentional operation into a silent no-op — the exact defect class this change exists to eliminate. An empty new_string means delete this text; an empty pr_url means clear the stored value.

Exclusions are scoped by tool and field, not by field name. An audit caught the first attempt exempting title globally, which would have let an empty title survive into memory_save and goop_create_pr where it means nothing. Tools not named in the policy get no exemption, so a future tool with a title argument gets the safe default rather than silently inheriting one written for something else.

content was considered and deliberately left unprotected: coalescing it produces a loud error, whereas protecting it would let an injected empty content silently wipe a document.

Only exact empty strings are affected. null, undefined, 0, false, [], {}, and whitespace-only strings pass through untouched, and the pass recurses into arrays and nested objects — every recorded failure involved an empty string nested inside an array element.

Documentation

Twelve tools brought into conformance, taking the total from 9 to 21 of 38. The clarifications worth calling out:

  • goop_read_db documents that "adl" is an accepted doc_type that can never resolve to a document, because that store holds an append-log of events
  • goop_search_docs documents that plural filters widen rather than narrow — they OR within a set and AND across sets
  • goop_append_chronicle states plainly that its piggyback writes are not atomic across stores, and what to do when one succeeds and another fails
  • goop_boot states that documents load only when doc_types is supplied
  • goop_reference states that section matching is exact, and that a miss returns the whole resource with a note rather than failing

Verification

2670 pass, 0 fail; typecheck clean. Independently audited twice — the first audit rejected the title scoping, which is fixed here and re-verified.

Correction

An earlier version of this description claimed that every agent session after the boundary landed reported no unauthored empty strings, offering that as the strongest evidence. That claim was wrong and is withdrawn.

The host loads this plugin from a built bundle at its install path and loads it once per session. The change in this branch is source in a worktree that was never built or deployed, so it has not executed in any session that reported on it. Those clean reports describe the old code. They were absence of evidence, and I read them as evidence.

What holds is the unit-level proof: the boundary is exercised directly, across both host paths, including the nested-in-array shape that caused the original failures, with the exclusion scoping pinned per tool.

What does not exist is end-to-end confirmation in a live host. That requires a rebuild at the install path and a restart, and it should be done before anyone relies on this being active.

The tell was a later agent being rejected over an injected empty string — impossible if the fix were live. Two independent audits passed this branch without catching it, because both reasoned about the source rather than asking which artifact the host was running.

hffmnnj added 8 commits August 4, 2026 15:53
Tool-call serialization in some hosts injects empty strings the caller never
authored — into status fields, mode selectors, and nested task_updates[]
entries. An empty string is never a legitimate value for those fields but
arrives as a present value, defeating the caller's intent: a mode conflict
the caller never created, an "invalid status" rejection, or "" stored as a
real value. Wave 2 rewrote goop_write_wave's description to warn against
passing empty strings; the next agent still failed the same way, because the
empty string is injected below the level any description can reach.

Add a single shared boundary (shared/coalesce.ts) that treats an exact "" as
absent (omitted) for fields where empty has no legitimate meaning, applied in
createTools so it runs on BOTH the V1 and V2 registration paths from one
source of truth. Recurses through arrays and nested objects; only exact "" is
affected (null/undefined/0/false/[]/{} and whitespace-only strings pass
through untouched); a non-empty value is never dropped.

Exempt an explicit, audited set of fields where empty is a documented
operation (EMPTY_STRING_LOAD_BEARING_KEYS): new_string/old_string (patch
delete + patch-mode activation on ""), pr_url/pr_branch/title (clear the
stored value). content is deliberately not exempt — an injected content:""
would silently destroy a document; coalescing yields a loud none-mode error.

goop_write_wave gains minimal tolerance for a status coalesced to absent in
task_updates[]/task_update (skip the no-op entry rather than storing
undefined), matching the existing !== undefined guard pattern already used
for optional status fields.

Regression test reproduces the exact Wave 2 verifier failure shape —
{wave_number, status:"", task_updates:[{task_index:0,status:""}],
verifications:[...]} — and asserts it now succeeds and records the
verifications. Exclusion tests prove empty new_string still deletes, empty
old_string still activates patch mode, and empty pr_url/pr_branch/title still
clear.
Add an "Empty-string argument coalescing" subsection under the House Tool-
Description Standard stating the behavior where callers will see it: what the
boundary does, why it exists (descriptions cannot fix host-injected empties),
the recursion contract, and the full exclusion table with the reason each
exempt field's empty value is load-bearing (new_string/old_string delete and
patch activation; pr_url/pr_branch/title clear). Notes that content is
deliberately not exempt.

Repin the prompt-audit byte-count and absolute-language assertions to the new
true values (references 171,170 -> 174,047 bytes; totalAbsoluteHits 319 ->
326, +7 contract invariants in the new section), with deltas documented in
the assertion comments. No assertion weakened or deleted.
…rect

Callers can now pick the right read surface from the description alone:
goop_read_db names the ADL trap (doc_type:adl returns 'No adl document
found' because the ADL is structured events, not a document row) and
redirects to goop_adl; goop_read_section states the separate-stores
boundary so a caller knows a goop_write_db document is not visible here
until a keyed section exists; goop_search_docs states that plural
filters OR within each set (widening, not narrowing) and AND across
types, eliminating the silent-wider-results surprise.
…st-try correct

Callers can now rely on the full mode and rejection contract before any
call. goop_write_db states all three modes (full/patch/batch) and the
four rejected combinations, plus that an empty content coalesces to
absent rather than wiping a document. goop_write_section adds the
write/delete action dimension, the items[]-rejected-for-delete rule, and
the _migrated-legacy-content reservation. goop_append_chronicle states
plainly that cross-store atomicity is unavailable across chronicle/ADL/
memory, that an aux failure after chronicle success leaves the chronicle
in place, and that the caller must retry the failed store separately.

All six document tools leave PENDING_CONFORMANCE; the three multi-mode
write tools enter HIGH_FRICTION_TOOLS because their rejection contracts
cannot fit under 700 without dropping a rule a caller needs to avoid an
error. Documentation and tests only; no runtime behavior changed.
…t-try correct

Bring goop_save_note, goop_search_notes, goop_reference, goop_boot,
goop_checkpoint, and goop_compact into conformance with the House
Tool-Description Standard (references/tool-reference.md): named sections
(WHEN TO USE / WHEN NOT TO USE / RETURNS), length bounds, recursive
argument .describe() on every field including nested items[] element
objects, and no empty-string-endorsing phrasing.

- goop_save_note: create/patch/batch modes with cross-field rejection;
  documents that items[] is now atomic (historically non-atomic). Allowlisted
  at 766 chars by parity with goop_write_db (same multi-mode write shape).
- goop_search_notes: documents the note_id escape hatch (bypasses ranking,
  returns full body) and the full/body_offset/body_limit window interaction.
- goop_reference: documents the exact case-insensitive section-match rule
  and that a miss returns full content rather than failing.
- goop_boot: adds .describe() to all 14 args; states documents load ONLY
  when doc_types is explicitly passed (no default set).
- goop_checkpoint: action/id/context described; save/load require id.
- goop_compact: states orchestrator-only, V1-only, next_step required and
  replayed as the resume action.

Removes all six from PENDING_CONFORMANCE; adds goop_save_note to
HIGH_FRICTION_TOOLS. Documentation and schema only; no runtime behavior
changes.
Bring memory_save, memory_search, and memory_forget to the house
tool-description standard and drop them from PENDING_CONFORMANCE
(17 -> 14).

memory_forget (allowlisted, 1074 chars): the destructive contract is
now unmissable. Documents the two mutually exclusive modes (id deletes
immediately and ignores confirm; query needs confirm:true), states
plainly that the operation is irreversible, and calls out the footgun
that the read-only preview caps at 20 rows while confirmed deletion
searches up to 100. Added to HIGH_FRICTION_TOOLS with justification.

memory_save (691 chars): documents what actually persists. Verifies
the per-type importance defaults (decision 7, note 4, else 5) at the
tool layer, the type=decision field-folding and fact auto-generation,
the id -1 graceful-degradation signal, and the deduplicate:true
reinforce-not-insert contract (importance=max(old,new), created_at
refreshed, content unchanged, no new row).

memory_search (695 chars): documents retrieval semantics honestly.
Filters AND-combine; concepts OR within the list as a substring match;
includeFieldNotes:true changes both membership and ranking via RRF
(k=60) and applies filters to the memory side only.

MH11/MH20 investigation: the 'query plus tag misses results that query
alone finds' observation is the intended AND-combination contract, not
a ranking bug. A record matching the query text but lacking the filter
is excluded by design. Confirmed under real FTS5 and pinned at both
the tool and manager levels. No algorithm change made or warranted.

Tests added:
- memory_forget: id precedence over query+confirm, confirm ignored on
  id path, query preview searches with limit 20, confirm-gates-query.
- memory_save: failed write degrades to id -1 rather than throwing.
- memory_search: limit clamp, empty-query no-results, concept filter
  narrows by design (tool level).
- features/memory (real FTS5): concept filter excludes a query match
  lacking the concept; substring/case-insensitive tag matching; and
  forgetByQuery deletes 30 > the 20-row preview ceiling.
Bring goop_setup, goop_spec, goop_infer_intent, goop_status,
goop_get_global_config, and slashcommand into conformance with the
house tool-description standard (WHEN TO USE / WHEN NOT TO USE /
RETURNS sections, recursive .describe() on every arg, length bounds).

PENDING_CONFORMANCE: 14 → 8.

Action-to-argument legality is now documented precisely for each tool:
- goop_setup: every action mapped to which args it reads vs ignores;
  scope is declared but silently ignored by every action;
  gitignoreGoopspec applies as a cross-action side effect regardless
  of action.
- goop_spec: file is read only by read; phase is ignored by all.
- goop_infer_intent: autoApply vs autoRun documented as separate
  mechanisms with different confidence gates (0.85 hard floor +
  threshold default 0.9 vs 0.75 autoRun floor); below-threshold is
  never an error.
- goop_status: verbose is declared but currently ignored.

Allowlisted (HIGH_FRICTION_TOOLS): goop_setup (1169), goop_spec (841),
goop_infer_intent (1152) — all carry mandatory mode/contract content
that cannot fit under 700.

Contract tests pin the three arguments-that-do-nothing (scope, phase,
verbose) and action-dependent arg legality for goop_setup.
hffmnnj added 6 commits August 4, 2026 17:10
…y correct

Bring ast_grep, difftastic, scip, background_command, background_status,
and background_cancel into conformance with the house tool-description
standard. Removes all six from PENDING_CONFORMANCE (8 -> 2); adds
ast_grep, scip, and difftastic to HIGH_FRICTION_TOOLS with per-tool
justifications.

Each description now carries the mandatory WHEN TO USE / WHEN NOT TO USE
/ RETURNS sections plus MODES/CAVEATS where applicable, and every
argument (including nested array item fields) carries a terminal
.describe(). Key load-bearing content added:

- ast_grep: documents the three modes (search / rewrite dry-run / rewrite
  apply) and the conditional no-op that apply:true without rewrite has no
  effect (-U is only appended inside the rewrite branch).
- scip: documents the action-dependent required field (symbol required for
  definitions/references/implementations, ignored by index) and that each
  action resolves a different binary (scip vs scip-typescript).
- difftastic: documents the alias-pair cross-field contract and the
  missing-binary-vs-no-differences distinction.
- background_command: keeps the verified timeout default (1800s/30min),
  the integer [1,86400] range with reject-not-clamp, and the kill-on-expiry.
- background_status: documents the lazy expiry sweep that marks timed-out
  without killing (eager timer owns the kill).
- background_cancel: documents the process-group SIGTERM->SIGKILL escalation.

No behavior changes; documentation and test-gate edits only.
…ORMANCE

generate_image (allowlisted, 1136 chars): full house-standard rewrite —
Purpose, WHEN TO USE/NOT TO USE, MODES (dryRun vs live), RETURNS, and
CAVEATS covering the png-only transparency constraint (green-screen +
local chromakey), default output path, count-suffix behavior, the
OAuth/credits cost model, and two dead arguments. mask and
outputCompression are declared on the schema but never read by execute()
nor forwarded to buildBody() — documented as 'Declared but not read by
the tool; supplying it has no effect.' Cross-field constraints surfaced
on out, outputFormat, and background so callers see them before the
call, not through a validation rejection.

goop_create_pr (allowlisted, 904 chars): documents the terminology gate
contract — scans title/body/branch, error-severity blocks while
warn-severity proceeds, code spans masked in title/body but never in
branch, reword-not-retry semantics with example rewrites. Dropped the
misleading merge-method sentence; documented honestly that no
merge-method argument is exposed and it is a repo setting on GitHub.

goop_spec (tightened from 841 to 632 chars, removed from allowlist):
the 3-action mode contract (file read only by read; phase ignored by
all) fits under 700 when the per-action file-ignored clauses are
collapsed into one. No contract lost.

PENDING_CONFORMANCE is now empty: all 38 tools face every predicate.
Full suite: 2690 pass, 0 fail.
The memory-save tool previously formatted decision rationale before passing it to the manager, which formatted the same fields again. Delegate content composition solely to the storage manager so persisted decision content and FTS weighting are not duplicated.

Changes:\n- Pass raw decision content from the tool\n- Pin manager composition and tool delegation contracts
Several action-dispatch errors identified a missing field without showing a corrected request. Include the tool context and a valid retry shape so callers can recover without consulting implementation details.

Changes:\n- Teach required state and blocker action payloads\n- Clarify memory deletion and setup reset confirmations
Reconcile secondary doc surfaces with what the code actually does so each
fact has one owner (the emitted schema) rather than stale copies.

AGENTS.md:
- Record the build-vs-source deployment gap in Gotchas: package.json
  points main/exports at src/index.ts, but the build script emits a
  dist/index.js bundle and the host loads that bundle, once per session,
  from an install path outside this worktree. Source edits here do not
  affect the running session; validating a behavior change needs a
  rebuild plus restart, and unit tests are the only in-session evidence.
- Fix the stale tool-factory count (30 -> 38), pinned by the registry
  tests; point at the emitted schema as the argument authority.
- Replace the restated ast_grep/difftastic/scip/generate_image/
  background_* argument and when-to-use lists with pointers to the
  emitted schemas. A restatement is a copy that silently goes stale;
  a prior version of this section fabricated model and inputFidelity
  args that generate_image never declared.

tool-reference.md (the maintained cheat sheet):
- Resolve two goop_write_wave contradictions that claimed
  verifications/traceability were 'not available alongside items batch
  mode'. They are supplied per-item inside each items[] entry;
  top-level side payloads alongside items[] are rejected, not dropped.
- Remove the phantom generate_image model/inputFidelity args and note
  mask/outputCompression are declared but ignored (owned by the schema).

prompt-audit test:
- Repin references.bytes 174_506 -> 174_965 to the true measured value.
  totalAbsoluteHits unchanged at 328 (no must/never/always/critical/
  only language added or removed).
hffmnnj and others added 5 commits August 4, 2026 18:16
Classify every registered tool for MODES and CAVEATS requirements so newly added tools cannot bypass the conditional section gate. Document the five additional mode-bearing tools and prove missing required conditional sections fail conformance.
Require mode sections for duplicate reinforcement, cross-store memory search, and draft pull-request creation. Document each opt-in path so callers can predict its execution and result.
Fix duplicated decision content and record the deployment gap
@hffmnnj
hffmnnj merged commit 5a6a657 into feat/high-risk-tool-contracts Aug 5, 2026
@hffmnnj
hffmnnj deleted the feat/empty-string-boundary branch August 5, 2026 12:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant